Digital Signatures for APIs | eBay Developers Program

Digital Signatures

FAQs

Due to regulatory requirements applicable to our EU/UK sellers, for certain APIs, developers need to add digital signatures to the respective HTTP call. This document specifies how these signatures are created and added to HTTP payloads.

APIs in scope

Signatures are required when the call is made for EU- or UK-domiciled sellers, and only for the following APIs/methods:

All methods in the Finances API
issueRefund in the Fulfillment API
GetAccount in the Trading API
The following methods in the Post-Order API:

Please note that signatures may be added for other APIs and/or for other sellers. eBay's system will ignore the signatures, but the API call will be accepted and handled in an ordinary manner.

Creating a payload signature

eBay's signature implementation is compliant with IETF standards:

NOTE: It is strongly recommended that the above standards be reviewed.

The following HTTP headers are added to each HTTP payload for in-scope APIs called on behalf of EU/UK domiciled sellers:

x-ebay-signature-key: REQUIRED
Content-Digest: CONDITIONAL
Signature: REQUIRED
Signature-Input: REQUIRED

eBay's Key Management API generates encrypted keypairs that are used to create the x-ebay-signature-key and the Signature headers.

The steps required to create each of the above four HTTP headers are listed below.

1. Create the x-ebay-signature-key header

The x-ebay-signature-key header always contains JWE.

Using the Key Management API, developers create the following keypairs:

Private Key
Public Key
Public Key as JWE

Important! In order to further ensure the security of confidential client information, eBay does not store Private Key values in any system. If a developer loses their Private Key they must generate new keypairs using the Key Management API.

The value of the x-ebay-signature-key header is the Public Key as JWE value that has been created by the Key Management API.

For example:

x-ebay-signature-key: eyJ6aXAiOiJERUYiLCJlbmMiOiJBMjU2R0NNIiwidGFnIjoiTjZIc2ItenlIXzZ4blFHQUhOdHByZyIsImFsZyI6IkEyNTZHQ01LVyIsIml2IjoiNjQ1Z0Rzc2lOYUZFb2pOWCJ9.rSWQSIKGgu_gAhLdG87fIpRYyI57KMQKYJpgQoXhPso.jvrOE0g2Q7A8h_Rj.uZsaA0VaVjL9HiciAilnNsos7Da-Fx5W3tr9sZO4qSPD-hB9t-lacy96lyeLiixs0nHXZ21iEwFYkqOllxpqW6eyJPb6lLDrnzg8Nx5AvizLagSDT35_3xBTu6EWf6x-lWBMKiBj8zo31wdjaGWMExcaQSPpwZxbJ3Z1sM4aZmHX7sjjnIT0V9kH1kAj0kD7uGuJ8KlMvrl011z68kJt-ilYG4FZn_Z5.CZzMDhEn1jqL45bYvbO3ig

2. Create the Content-Digest header

NOTE: When no HTTP payload is included (e.g., for a GET call,) this header is not required.

When an HTTP payload is included, this header provides an SHA-256 digest over the HTTP payload.

To add the Content-Digest header, calculate an SHA-256 digest over the HTTP payload (in UTF-8 character encoding). While the specification allows adding more than one digest (e.g., both SHA-256 and SHA-512,) only the SHA-256 is needed in our case.

For complete information about how to add the Content-Digest header, refer to Section 2, The Content-Digest Field, of RFC9530.

To review an example of adding a Content-Digest header, refer to Section B.1. Server Returns Full Representation Data, of RFC9530.

Consider the following payload:

{"hello": "world"}

In this case, the value of the Content-Digest header will be:

sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=:

3. Create the signature base

The signature base is a US-ASCII string containing standard HTTP message components covered by the signature. To create the signature base, the signer or verifier concatenates together entries for each component identifier in the signature's covered components (including their parameters).

For complete information, including the detailed algorithm to create the signature base, refer to Section 2.5, Creating the Signature Base, of RFC9421.

For additional information about creating individual pseudo headers that may be part of the signature base, refer to Section 2.2, Derived Components, of RFC9421.

4. Create the Signature header

The Signature header is created using the Private Key value generated by the Key Management API (x-ebay-signature-key header) and the signature base.

The value of the Signature header is created as described in Section 3.1, Creating a Signature, of RFC9421.

Depending on the cipher that is to be used, refer to the following specific sections of RFC9421 for complete information:

To review examples illustrating how signature headers are created, refer to Appendix B, Example Keys, of RFC9421.

5. Create the Signature-Input header

This header indicates which headers and pseudo-headers are included, as well as the order in which they are used when calculating the signature.

For complete information about creating the Signature-Input header refer to Section 4, Including a Message Signature in a Message, of RFC9421.

The value of the Signature-Input header is:

sig1=("content-digest" "x-ebay-signature-key" "@method" "@path" "@authority");created=1658440308

NOTE: The value assigned to the parameter created is the Unix timestamp when the signature is first created.

If no HTTP payload is included, the header would be:

sig1=("x-ebay-signature-key" "@method" "@path" "@authority");created=1658440308

How to test the signature

The Sandbox environment can be used to test the signature mechanism. Call the Key Management API in the Sandbox to create the Private Key, Public Key. and Public Key as JWE for testing a signature in the Sandbox.

Important! In order to test digital signatures in the Sandbox environment, the domicile of the sandbox user MUST be set to be one of the EU countries or the UK (e.g., "DE" or "GB"). Only in this case will the digital signature be required and verified.

For additional information about creating sandbox users, refer to Create a test Sandbox user.

NOTE: If preferred, open source sample code has been implemented that enables signatures to be verified using test keys. This code can be deployed using a Docker container. For complete information, refer to README.

Error codes

When issuing a call to any in-scope API in either the Production or Sandbox environment, if the request is improperly formatted or does not include all required headers, an error will be returned. Refer to the following table for information about these errors.

Code	Meaning
215000	Missing content-digest header
215001	Missing x-ebay-signature-key header
215002	Internal errors as fetching master key
215003	Internal errors as validating digital signaure
215101	Missing content digest
215102	Missing payload
215103	Parsing value of sha failed
215104	Base64 decoding sha failed
215105	Incorrect content digest of sha-256
215106	Incorrect content digest of sha-512
215107	Incorrect content digest of sha
215108	Content digest validation failed
215109	Missing parameters (internal error)
215110	Missing content-digest header
215111	Missing signature header
215112	Missing signature-input header
215113	Invalid timestamp in signature parameters
215114	The create time of signature parameters is not in right range
215115	Decrypting JWE failed
215116	Incorrect JWE format
215117	The appid in signature doesn't match app in token
215118	Missing pkey in JWE
215119	Decoding public key failed
215120	Signature validation failed
215121	Signature validation failed
215122	Signature validation failed

Digital Signature SDKs

To simplify the process of generating digital signature headers, eBay has developed the following SDKs. The SDKs also provides methods to validate digital signature headers.

Additional information about each of the SDKs is available in their respective README files.